Skip to content

Enable Scalafmt in Scaladocs - #4842

Open
satorg wants to merge 8 commits into
typelevel:mainfrom
satorg:scalafmt-docstrings
Open

satorg wants to merge 8 commits into
typelevel:mainfrom
satorg:scalafmt-docstrings

Conversation

@satorg

@satorg satorg commented Mar 9, 2026 •

Copy link
Copy Markdown
Contributor

The only significant change is in .scalafmt.conf:

- docstrings.style = keep
+ docstrings.style = Asterisk

After that, sbt prePR was applied.

Some manual fixes in Scaladoc were also necessary – not because Scalafmt "broke" something, but because a few existing Scaladocs were incorrectly formatted and were therefore treated as plain text. For example:

Details

A table defined in plain text like that:

Benchmark                                       Mode  Cnt         Score        Error  Units
ParTraverseBench.eitherParBitraversePointfree  thrpt   50  20201469.796 ± 143402.778  ops/s
ParTraverseBench.eitherParBitraversePointfull  thrpt   50  24742265.071 ± 133253.733  ops/s
ParTraverseBench.eitherParTraversePointfree    thrpt   50   1150877.660 ±  10162.432  ops/s
ParTraverseBench.eitherParTraversePointfull    thrpt   50   1221809.128 ±   9997.474  ops/s

had to be enclosed into {{{ }}} in order to make a pre-formatted text. Otherwise, it turns into a mess.

Why this change?

Two reasons:

  1. Autoformatting helps maintain a consistent style across the repository, and Scaladoc is part and parcel of that.
  2. It is especially valuable in the AI era, as it reduces unnecessary noise in PRs that AI agents tend to generate.

Why this particular style?

docstrings.style = Asterisk aligns best with the majority of existing Scaladocs in the repository.


UPDATE: this legacy setting was also removed from .scalafmt.conf:

docstrings = JavaDoc

It has no effect because the following

docstrings.style = Asterisk

overrides it.

@satorg
satorg force-pushed the scalafmt-docstrings branch from 54c1555 to 7691397 Compare March 9, 2026 04:30
@satorg
satorg force-pushed the scalafmt-docstrings branch from 7691397 to 77d1208 Compare March 22, 2026 22:57
@satorg
satorg force-pushed the scalafmt-docstrings branch from 77d1208 to 8e82f5b Compare April 20, 2026 04:56
@satorg
satorg force-pushed the scalafmt-docstrings branch from 8e82f5b to 151c17e Compare May 14, 2026 21:40
@satorg
satorg force-pushed the scalafmt-docstrings branch 2 times, most recently from 57b489a to 20c54d1 Compare September 22, 2026 22:12
@satorg satorg self-assigned this Sep 22, 2026
@satorg
satorg force-pushed the scalafmt-docstrings branch from 20c54d1 to 24d4b16 Compare November 7, 2026 02:46
satorg and others added 6 commits November 6, 2026 21:28
Restore sentence boundaries that were lost when scalafmt reflowed
docstrings, keep inline code spans and links on a single line, put
equations and code samples back into {{{ }}} blocks, and align the
@example formatting in syntax/either.scala with ApplicativeError.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant